{% extends "base.html" %}
{% block content %}

<div style="width: 80%">
<p>
  You probably reached here by clicking on the Documentation link. This section
  will explain all the methods supported by gaeQuery
</p>

<p>
  The idea is to support most of the methods exposed by the AppEngine Python API
  for <a href="http://code.google.com/appengine/docs/python/datastore/queryclass.html">Queries</a>
  and <a href="http://code.google.com/appengine/docs/python/datastore/modelclass.html">Model</a>
  instances. However, as of this writing only some of the key (read essential) methods are supported.
</p>

<p>
  <b>The following methods are supported on:</b>
  <br/><br/>
  <b>Query instances:</b>
  <ol>
    <li>filter()</li>
    <li>order()</li>
    <li>get() <sup><a href="#footnote1">1</a></sup></li>
    <li>fetch() <sup><a href="#footnote1">1</a></sup></li>
  </ol>

  <b>Model instances:</b>
  <ol>
    <li>key()</li>
    <li>put() <sup><a href="#footnote1">1</a></sup></li>
    <li>remove() <sup><a href="#footnote1">1</a></sup>: This is the equivalent of delete() in Python</li>
  </ol>
    
  <b>Key Instances:</b>
  <ol>
    <li>kind()</li>
    <li>name()</li>
    <li>toString(): This is the equivalent of str(entity.key()) in Python</li>
  </ol>
  
</p>
<br/>

<p>
  <b>The following data types are allowed:</b>
  <ol>
    <li>Integer</li>
    <li>String</li>
    <li>Homogeneous Lists of Strings and Integers</li>
    <li><a name="datetimeWorkaround"></a>You can emulate DateTime types by storing the datetime as a string 
        formatted as "YYYY-MM-DD HH:MM:SS" with everything zero(0) padded
        and HH should be in 24 hour format. You can perform inequality 
        checks with such a format as well.
    </li>
  </ol>
</p>

<p>
  <b>Example code (yumm!!):</b>
  <br/><br/>
  
  To create a new entity of type <b>MyUser</b>, just do:
  <pre>
  var obj = $gae("MyUser").create();
  </pre>
  In future releases, support for setting the <b>key_name</b> will be added.<br/><br/>
  
  You can now set properties on it just like you would on a normal javascript 
  object (be a bit carefull though; use firebug, etc... to see attributes that 
  are already set, and DO NOT overwrite them):
  <pre>
  obj.firstName = "Sheldon";
  obj.lastName  = "Cooper";
  obj.whereCanIfindHim = "The Big Bang Theory";
  obj.roomMate = "Leonard";
  </pre>
  
  Now, save the object:
  <pre>
  obj.put();
  </pre>
  
  But how do we know if the save was successful??
  <pre>
  var feedback = new GaeDeferred().addCallback(function() {
      alert("Success!!");
  }).addErrBack(function() {
      alert("Something broke :(");
  });
  obj.put(feedback);
  </pre>

  Am I boring you?? Just one last bit... Find all <b>Coopers</b> in the world!! ;)
  <pre>
  $gae("MyUser").filter("lastName =", "Cooper").fetch(100,0);
  </pre>
  
  Woops, forgot to display the results!!
  <pre> 
  var cb = new GaeDeferred().addCallback(function(data) {
      console.log(data);
  }).addErrBack(function() {
      alert("Something broke :(");
  });
  $gae("MyUser").filter("lastName =", "Cooper").fetch(100,0,cb);
  </pre>

</p>

<p>
  <b>How does it work?</b><br/>
  All models are of type db.Expando internally and all properties are dynamic properties.
  Models are created on the fly as and when required. The code is licensed under the 
  GNU LGPL and is available for download <a href="http://code.google.com/p/gaequery/">here</a>.
</p>

<p>
  <b>Limitations (there are many; please contact me if and when you find more):</b><br/>
  <ol>
    <li>Composite Indexes are not supported</li>
    <li>All attributes are indexed; since everything is a dynamic property</li>
    <li>No support for DateTime, but there is an excellent alternative (see 
   	<a href="#datetimeWorkaround">above</a>)</li>
   	<li>No support for parent() queries. You can work around this too.
   	I'll write about this in a bit</li>
   	<li>No support for key only queries. Something that needs to be thought of</li>
   	<li>No support for key_name queries. This will get added soon</li>
   	<li>No support for multi-put/get as of now</li>
  </ol>
</p>

<br/>
<p>
<b>Footnotes:</b>
<ol>
  <li><a name="footnote1"></a>The functions get(), fetch(), put() and remove() additionally 
  	take an extra parameter which is a GaeDeferred object which is similar to the 
  	<a href="http://api.dojotoolkit.org/jsdoc/1.3/dojo.Deferred">dojo.Deferred</a> object. 
  	However, GaeDeferred has only 2 methods available: addCallBack() and addErrBack().
  </li>
</ol>
<br/>
</div>
{% endblock %}
